K 線 WS 推送

連線位址：wss://stream.valuescan.ai/stream/ws/openapi/kline

---

一、概述

K 線 WS 推送用於持續接收指定代幣的即時秒級 K 線資料。客戶端建立 WebSocket 連線並完成訂閱後，將收到已訂閱代幣的 K 線訊息。

主要特性：

• 即時推送：推送當前 K 線即時變化，不僅限於已閉合 K 線。
• 秒級資料：目前僅推送 bucketType=1s 的秒級 K 線。
• 按連線訂閱：每條 WS 連線獨立維護訂閱列表。
• 斷線重連：連線斷開後，客戶端需要重連並重新訂閱。

說明：推送內容為即時行情變化，不保證每個代幣每秒都有訊息。若需要 1m、5m、1h 等其他週期，請基於收到的秒級資料自行聚合。

---

二、連線位址

GET wss://stream.valuescan.ai/stream/ws/openapi/kline

---

三、鑑權方式

K 線 WS 在建立連線時完成鑑權，鑑權參數放在 Query String 中。

參數	類型	必需	說明
apiKey	string	是	ValueScan Access Key
sign	string	是	HMAC-SHA256 簽章
timestamp	long	是	毫秒級 Unix 時間戳
nonce	string	是	隨機字串（防重放）

簽章演算法：

sign = HMAC-SHA256(SK, timestamp毫秒 + nonce)

範例：

import hashlib
import hmac
import time
import uuid

AK = "your-access-key"
SK = "your-secret-key"

timestamp = str(int(time.time() * 1000))
nonce = uuid.uuid4().hex
sign = hmac.new(
    SK.encode(),
    (timestamp + nonce).encode(),
    hashlib.sha256,
).hexdigest()

---

四、點數消耗

• 計費方式：按用戶收費，WS 連線期間，每 30 分鐘收費 100 點數。
• 額度不足處理：點數不足時，連線將收到標準錯誤訊息並斷開。

已成功扣費的 30 分鐘計費週期內，連線可繼續使用；下一計費週期點數不足時連線會斷開。

---

五、連線與訊息格式

1. 連線成功

連線建立並通過鑑權後，會收到：

{
    "type": "connected",
    "payload": {
        "requestId": "7b8a0b7f9f4a4f2c91f9e1e48c36d5b2"
    }
}

2. 訂閱

客戶端發送：

{
    "type": "subscribe",
    "payload": {
        "items": [
            {
                "vsTokenId": 1
            }
        ]
    }
}

訂閱確認：

{
    "type": "subscribed",
    "payload": {
        "items": [
            {
                "vsTokenId": 1
            }
        ]
    }
}

3. 取消訂閱

取消指定代幣：

{
    "type": "unsubscribe",
    "payload": {
        "items": [
            {
                "vsTokenId": 1
            }
        ]
    }
}

取消當前連線的全部訂閱：

{
    "type": "unsubscribe",
    "payload": {}
}

取消訂閱確認：

{
    "type": "unsubscribed",
    "payload": {
        "items": []
    }
}

4. K 線推送

K 線訊息：

{
    "type": "data",
    "payload": {
        "vsTokenId": 1,
        "bucketType": "1s",
        "tradePair": "BTCUSDT",
        "klineType": "01",
        "time": 1781686187000,
        "open": 64873.11,
        "close": 64877.29,
        "high": 64877.3,
        "low": 64873.11,
        "volume": 0.27783,
        "value": 18023.8032114,
        "uniqueId": "01:BTCUSDT:1781686187000:1s"
    }
}

payload 欄位說明：

欄位	類型	說明
vsTokenId	long	代幣 ID
bucketType	string	K 線時間窗口，固定為 1s
tradePair	string	預設 USDT 交易對
klineType	string	K 線來源類型，詳見 KlineType 列舉
time	long	K 線時間，毫秒時間戳
open	number	開盤價
close	number	收盤價
high	number	最高價
low	number	最低價
volume	number	成交量
value	number	成交額
uniqueId	string	推送唯一識別，可用於客戶端去重

---

六、訂閱限制

限制項	上限	說明
單用戶 K 線 WS 連線數	50 條	超過限制會回傳限流錯誤
單條 WS 連線訂閱代幣數	200 個 vsTokenId	相同 vsTokenId 去重計數

建議客戶端根據訂閱規模進行分流：單連線訂閱數量接近 200 時，拆分到新的連線中。

---

七、錯誤訊息

WS 建連後的業務錯誤使用統一 JSON 訊息：

{
    "type": "error",
    "payload": {
        "code": 40001,
        "message": "Required parameter is missing",
        "requestId": "a7d7ce3053e140dca91d93df173648f8"
    }
}

常見錯誤碼：

code	說明
20001	API Key 缺失
20012	時間戳過期
20021	簽章驗證失敗
40001	必填參數缺失，例如訂閱項缺少 vsTokenId
40002	參數格式或取值不合法
60001	限流，例如連線數或訂閱數超過上限
70001	OpenApi 點數不足

建連階段的鑑權錯誤會以 HTTP 200 回傳業務 JSON，回應體中的 code 表示實際錯誤原因。

---

八、接入範例

Python

依賴：

pip install websocket-client

範例程式碼：

import hashlib
import hmac
import json
import time
import uuid
import urllib.parse
import websocket

AK = "your-access-key"
SK = "your-secret-key"
VS_TOKEN_ID = 1

timestamp = str(int(time.time() * 1000))
nonce = uuid.uuid4().hex
sign = hmac.new(
    SK.encode(),
    (timestamp + nonce).encode(),
    hashlib.sha256,
).hexdigest()

params = urllib.parse.urlencode({
    "apiKey": AK,
    "sign": sign,
    "timestamp": timestamp,
    "nonce": nonce,
})

url = f"wss://stream.valuescan.ai/stream/ws/openapi/kline?{params}"

ws = websocket.create_connection(url, timeout=10)

try:
    connected = json.loads(ws.recv())
    print("connected:", connected)

    ws.send(json.dumps({
        "type": "subscribe",
        "payload": {
            "items": [
                {"vsTokenId": VS_TOKEN_ID}
            ]
        }
    }))

    while True:
        message = json.loads(ws.recv())
        msg_type = message.get("type")

        if msg_type == "subscribed":
            print("subscribed:", message)
        elif msg_type == "data":
            kline = message["payload"]
            print(
                f"[{kline['tradePair']}] "
                f"time={kline['time']} close={kline['close']} volume={kline['volume']}"
            )
        elif msg_type == "error":
            print("error:", message)
            break
finally:
    ws.close()

---

九、斷線重連建議

K 線 WS 連線可能因網路波動、服務維護或點數不足而斷開。建議客戶端：

1. 監聽連線關閉事件。
2. 使用指數退避策略重連，避免短時間高頻重試。
3. 重連後重新產生 timestamp、nonce、sign。
4. 重新發送訂閱訊息恢復訂閱列表。
5. 使用 uniqueId 對已處理的 K 線訊息做冪等去重。

範例重連間隔可設為：1s、2s、4s、8s，最大不超過 60s。